COMMENT ⊗   VALID 00003 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002			Implementation Guide to REVED
C00007 00003		At the time of this writing, the code is largely uncommented but
C00011 ENDMK
C⊗;
		Implementation Guide to REVED

	If you want to know how to use REVED, you are looking in the wrong
place.  Run it and ask it for help instead.  If you want to know how to
get to something in the set of routines that collectively constitute REVED,
then you have come to the right place.  The first piece of useful information
is that a fresh version may be compiled by giving the monitor command
LOAD REVED←@MAKREV.CMD
Two necessary files are not named there in MAKREV; these are:
	HEADER.SAI
	JAMLIB.REL[SUB,SYS]
Files that are currently named there are:
	PSIEVE.SAI	(Generated by PSGEN.SAI)
	PRIMER.SAI
	UNIT.SAI
	APRL.FAI
	IMPULS.SAI
	TREE.SAI
	FETCH.SAI
	PAPER.SAI
	INSTRU.SAI
	CURSOR.FAI
	DISPLA.FAI
	FACADE.SAI
Each one of these implements one facet of REVED's capabilities.  The top level
routine is in FACADE, which is then responsible for calling on whoever else it
needs.  For displaying text, DISPLA is the place to go, except in the special
case that you want to put a character in column 0, in which case you should try
CURSOR.  Files suitable for input to KLMUS or whatever the current music
compiler name is are generated in INSTRU, which takes the tree as an argument.
Most of PAPER is now superfluous, with the most important exception being the
PPSIZE routine.  It used to handle pieces of paper, which have been superceded
by DISPLA.  The routines in FETCH are mostly boolean procedures which take a
string as argument, and try to gobble up a certain type of token from it,
returning TRUE on success.  Token types include file names, YES/NO's, real or
integer numbers, etc.  Naturally these are called to understand input commands.
This allows FACADE to be device independent and to work in terms of conceptual
entities instead of strings.  Along the same lines, TREE implements all the
necessary operations for handling reverberator trees.  These trees are further
composed of unit reverberators, an abstraction supported by the routines in
UNIT.  The table of prime numbers in the mechanically generated file PSIEVE is
required for certain operations on units.  To make a new PSIEVE, just execute
PSGEN.  This table is accessed thru the routine in PRIMER, which does various
searches through the primes.  Using some graphics display routines from JAMLIB
and the all-pass reverberator routine in APRL, the routines in IMPULS generate
an impulse response for a list of units which can be constructed by other
routines in the same module.  The HEADER file is REQUIRED as a prefatory source
file by all of the SAIL routines, and just contains a few favorite macro
definitions for convenience.
	At the time of this writing, the code is largely uncommented; but
since it is broken down into small pieces -- each of which implements an
abstraction of some sort -- and since it is written in terms of mnemonically
named routines (at least, they're as mnemonic as I could think of given
that all of the external names had to be unique to 6 characters), it should
be bearable, if not readable.  Basic concepts are implemented using SAIL's
record handling facilities, treating a record as an instantiation of some
conceptual entity which is operated upon by routines provided for the
purpose.  Thus, for example, unit reverberators are made programming entities
by allocating a record for each unit and providing the "get_spec" and
"set_spec" routines to interact with them.  (Several other routines are
also provided, but these are the most important.)  These routines examine
or reset the value of some theoretical parameter of a unit reverberator,
including parameters which are not physically present in the record which
represents an instantiation.  Hopefully the chunks have been chosen and
implemented in such a way that they may be easily extracted and modified
for other uses (or extended in situ).  Each file is prefaced with a
description of the abstraction the routines in it implement.  Furthermore,
each routine is described at the start of that routine.

	Machine efficiency was a minor consideration in the design of this
code, and presumably it can be improved where necessary.  However it was
my feeling -- apparently borne out in practice -- that most inefficiencies
account for so little time that it's not worth complicating the code to
remove them.  A case in point is the inner loop of the display algorithm
for impulse responses: a hand-coded START_CODE version ran very little
faster even under the most trying circumstances.  Therefore the general
criterion was that a little human clarity is worth a lot of machine time.